Building User Interfaces of Atlassian Apps with Atlaskit and AUI
--
This article was originally written by Deviniti Marketing Manager Dzmitry Hryb.
This year’s Atlassian App Week Key Largo was dedicated to UX design, due to ongoing implementation of the new interface in Jira. Developers from the ecosystem could learn about AUI and Atlaskit, the building blocks for it, from their creators. After the fruitful collaboration that Deviniti Apps team had had with Atlassians and other Solution Partners in Miami, we decided to write an article about how these libraries are developed and how you can use them in building apps’ user interfaces.
What are Atlaskit and AUI and what’s the difference between them?
Basically, Atlaskit and AUI are UI component libraries which help implement Atlassian Design Guidelines and maintain seamless user experience throughout all the Atlassian software. AUI is the “elder brother”, as it started back in 2008 as an effort to share common UI solutions across Atlassian products. It was built on low-level API of HTML and CSS, and distributed via Atlassian Plugins Framework. Atlaskit started 2 years ago as an effort to implement ADG3 designs for all Atlassian Cloud products, which are built on top of React. Atlaskit team lead Jony Cheung admits that it started as a repository of leaf UI components and un-opinionated about how components are used. Nevertheless, it was already a better fit to modern front-end development due to being React-based and open-sourced through a Bitbucket repository.
Even though Atlaskit Core and AUI contain different sets of components and used to provide an implementation of ADG for Cloud and Server hosting options respectively, the two libraries are somewhat complementary. If you don’t want to use React, you’ll still be able to play safe with AUI in your apps as soon as it will get updated to the latest Atlassian Design Guidelines and thus provide identical styling to Atlaskit. Chris Darroch’s team have recently released AUI 7.9, which re-skins dropdown menus — other components will be updated over time. In its turn, Atlaskit features a reduced UI pack, which is designed to allow you to use some ADG3 styling easily without opting in to using React. Instead, it provides a CSS file as its main export, allowing you to add classes and meta-properties to HTML to get the styling. This approach seems logical when it comes to updating existing apps to ADG3, but we took one step further and re-wrote big parts of our apps with the new Jira’s UX and UI in mind. So we’re one of the few Marketplace vendors who decided to make use of Atlaskit in apps for Jira Server.
Atlaskit and AUI help implement Atlassian Design Guidelines and maintain seamless user experience throughout all the Atlassian software.
Why use them?
The main reason to use these libraries is that Atlassian relies on them to provide consistent and performant user experience across their products. Atlaskit developer Trey Shugart says:
‘Over the last 2 years, almost all single-page applications built in the Atlassian Cloud use React and Atlaskit. As the library matures, Atlassian products and ecosystem vendors lean in more heavily into it.’
If it comes to AUI, Chris Darroch noticed a minimum of 40% utilization of this one in every Atlassian product UI in 2017. Each of them ships AUI’s CSS reset and basic styles, most use dropdowns and inline dialogs from the library, and the remaining components are used occasionally. The styles are shared across all components, built into them and tested, so you can be sure they will be displayed in the same way for every user and on every browser. If anything, you can always contribute to the projects and submit your fixes or even new components.
You should take into account, though, that some components’ behaviors had been built before an understanding of the product team’s expectations was established, which led to them not being used widely or at all. AUI’s asynchronous dropdowns are a good example of this: the feature was built expressly for Jira, but apparently, the software does not use the behavior as it caches the response forever, whereas it needs the content to change each time the dropdown is opened.
The second reason is that ready-made and instantly ADG compatible components are good building blocks for custom UI elements. The fact of using Atlaskit or AUI alone saves you plenty of time on ‘reinventing the wheel’ and constructing something that already exists in the library and is ready to go with. But the possibility to customize makes them an even better solution to build the front end of Atlassian apps.
An example of Atlaskit implementation in Atlassian apps
After a year of reworking our apps’ UI, 41% of them have React and Atlaskit components implemented, and almost every new feature uses them in its UI. Extension for Jira Service Desk and Dynamic Forms for Jira have been almost completely re-written in React.
One of our custom components built on top of React and Atlaskit is JQL Autocomplete Input, used among others to help define custom filters for the columns and rows of the Traceability Matrix in our latest app, ReqFLO. It uses FieldBase, Input, and DropList along with some icons and styles from Atlaskit, and we’ve developed the autocomplete behavior ourselves to connect with these components. The resulted field highlights errors and provides suggestions to the queries based on previous input.
Here’s how the render looks like:
And here’s how it behaves in the user interface:
You can download this component from our own public Bitbucket repository, which we plan to update with other custom components we build on top of Atlaskit.
The dark side of the moon
Despite all the goodness that the components from Atlaskit and AUI provide, concerns may arise about their use.
- Some of the components have been too heavy to implement — if that’s the case for you, Jony Cheung and Chris Darroch recommend to keep them updated to the latest version and use webpack 4. Bundles’ size is another pitfall, which Atlassian promised to fix in the upcoming releases.
- On Server instances, AUI has been different from Atlaskit in terms of styling — this is to be solved in AUI 8, as Daz mentioned in the discussion on the topic.
- Dependencies and API compliance can limit the use of some components, especially on Cloud, and some older browsers like IE11 are not supported at the moment. A way to fix it could be the use of babel-polyfill, but it could also cause problems in Jira itself due to the script affecting the global scope.
- In addition, due to the recent AUI license change, you can use AUI 7.x only for developing Atlassian Marketplace apps. You should stick to AUI 6.x if you want to build something outside of the Atlassian Ecosystem, or wait until AUI 8.
These are not the only things to be improved in these libraries. As Chris Darroch stated,
‘AUI has had a large number of contributions over time, each with disparate coding philosophies. The results have been mixed. The AUI component APIs are not always consistent, nor easy to consume, especially compared to more recent component libraries such as Polymer’s Iron Elements’.
AUI’s pain points have been its monolithic nature, low-level API, and the distribution model on P2. The AUI team declares to be addressing these pain points in upcoming major releases, moving it in a direction that’s more sympathetic to the needs of front-end development in 2018. The plan is to iteratively add web component APIs for all AUI components, and make individual components consumable rather than a monolithic library.
In his turn, Jony Cheung admitted that Atlaskit components need to walk the fine line balancing between being opinionated about best practices implementation and providing the right level of extensibility.
From now on, Atlaskit Core components will work on better logical groupings of components and design primitives, provide a consistent API with default props and an ability to setup controlled props in order to override default behaviors as needed.
Other significant improvement areas are compose-ability of components through an ability to set render props, as well as theming flexibility and adding more common design patterns to the library.
What’s your experience with Atlaskit and AUI? Share it in the comments and ask questions if you’d like to know more!
As an Atlassian Platinum Solution Enterprise Partner and a Platinum Marketplace Partner, we’ve been working hard on helping improve the user experience of Jira Service Desk and Jira Software for the last 15 years. With our expert services and dedicated apps on the Atlassian Marketplace, we’ve enhanced the overall quality of work comfort and customer service in over 5000 companies around the globe.
If you want to learn more app development tips and tricks, make sure to check out other articles available on Deviniti Technology-Driven Blog:
